{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3. Properties\n",
    "Properties files are used to set the various settings throughout NeuRec. You can pass a properties file to NeuRec as follows:\n",
    "\n",
    "```python\n",
    "neurec.setup('neurec.properties')\n",
    "```\n",
    "\n",
    "> Before running NeuRec, you must create and pass a properties file to the setup() function.\n",
    "\n",
    "## Properties Structure\n",
    "Properties files should start with a **DEFAULT** section. This lets NeuRec know that these are the properties to fallback on, for example:\n",
    "\n",
    "```\n",
    "[DEFAULT]\n",
    "data.input.path=neurec\n",
    "data.input.dataset=Ciao\n",
    "data.column.format=UIRT\n",
    "data.convert.separator=','\n",
    "data.convert.binarize.threshold=0\n",
    "recommender=apr\n",
    "```\n",
    "\n",
    "We can override the DEFAULT section by creating a new section with different property values. In the example below, we override the recommender property using the MLP section, setting its value from apr to mlp.\n",
    "\n",
    "```\n",
    "[DEFAULT]\n",
    "data.input.path=neurec\n",
    "data.input.dataset=Ciao\n",
    "data.column.format=UIRT\n",
    "data.convert.separator=','\n",
    "data.convert.binarize.threshold=0\n",
    "recommender=apr\n",
    "\n",
    "[MLP]\n",
    "recommender=mlp\n",
    "```\n",
    "\n",
    "To let NeuRec know which section to use, pass the section name to the setup() function:\n",
    "\n",
    "```python\n",
    "neurec.setup('neurec.properties', 'MLP')\n",
    "```\n",
    "\n",
    "Now, NeuRec will read the MLP section first, in this case using the recommender value to create an MLP model.\n",
    "\n",
    "> Defining sections can be useful for quickly changing between properties.\n",
    "\n",
    "## List Model Properties\n",
    "To find out which properties a model requires, you can use the **listProperties()** function like so:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'name': 'layers', 'type': 'to_list'},\n",
       " {'name': 'learning_rate', 'type': 'float'},\n",
       " {'name': 'ispairwise', 'type': 'to_bool'},\n",
       " {'name': 'learner', 'type': 'str'},\n",
       " {'name': 'topk', 'type': 'int'},\n",
       " {'name': 'epochs', 'type': 'int'},\n",
       " {'name': 'num_neg', 'type': 'int'},\n",
       " {'name': 'reg_mlp', 'type': 'float'},\n",
       " {'name': 'batch_size', 'type': 'int'},\n",
       " {'name': 'loss_function', 'type': 'str'},\n",
       " {'name': 'verbose', 'type': 'int'},\n",
       " {'name': 'num_neg', 'type': 'int'}]"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import neurec\n",
    "\n",
    "neurec.listProperties('mlp')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding New Properties\n",
    "To define new properties in NeuRec so that it can be used in a model, add the property to the **data/properties.py** file. This file lists all the available properties and their type, which is used to cast the value when being read from the properties file. You can use the following helper functions to correctly convert property values.\n",
    "\n",
    "### to_bool\n",
    "This function converts a string to a boolean type. The following string values are allowed:\n",
    "\n",
    "* true\n",
    "* yes\n",
    "* y\n",
    "* 1\n",
    "* false\n",
    "* no\n",
    "* n\n",
    "* 0\n",
    "\n",
    "An example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from neurec.util.helpers import to_bool\n",
    "\n",
    "is_pairwise = \"true\"\n",
    "\n",
    "to_bool(is_pairwise)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### to_list\n",
    "This function converts a string to a list, casting the elements inside the list to a defined type, such as int or float. The string must have the following structure: \"[ ]|type\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0.8 0.2]\n",
      "float64\n"
     ]
    }
   ],
   "source": [
    "from neurec.util.helpers import to_list\n",
    "\n",
    "ratio = \"[0.8,0.2]|float\"\n",
    "\n",
    "ratio_list = to_list(ratio)\n",
    "\n",
    "print(ratio_list)\n",
    "print(ratio_list.dtype)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
